Hi Langfuse team,

Thanks for this awesome SDK. I have been using it to test an application with agents involved. However, since the application is under rapid development phase, I made some changes to the exporter so that I can do quick local debugging without setting up the whole Langfuse services. I figured that these changes might be useful to someone else, so I submitted this PR.

This PR introduces an option to export OpenTelemetry traces to a local file, intended to improve the local development and debugging workflow.

Advantages:

• Easier Debugging: It allows developers to inspect raw trace data locally without needing a connection to a Langfuse backend, which is useful for debugging instrumentation.
• Offline Development: Enables validation of tracing implementations in environments with restricted or no network access.
• Simplified Analysis: Exported trace files can be easily shared, analyzed with custom scripts, or ingested into other tools.
• Cleaner Dev Environment: Prevents sending test or incomplete data to a production Langfuse project during development.

This feature is opt-in and does not alter the default behavior of the exporter.

To enable local file export, set the LANGFUSE_OTEL_TRACES_EXPORT_LOCAL_FILEPATH environment variable. Ensure that the LANGFUSE_OTEL_TRACES_EXPORT_PATH variable is unset to avoid conflicts, which also protects the default exporter behavior. The local exporter is only effective when the LANGFUSE_OTEL_TRACES_EXPORT_LOCAL_FILEPATH is set AND the LANGFUSE_OTEL_TRACES_EXPORT_PATH is unset.

# Set the local file path
export LANGFUSE_OTEL_TRACES_EXPORT_LOCAL_FILEPATH="/path/to/my/traces.json"

# Unset the remote export path
unset LANGFUSE_OTEL_TRACES_EXPORT_PATH

Disclaimer: Experimental PR review

Greptile Summary

This PR adds local file export for OpenTelemetry traces to support offline debugging. While the feature idea is valuable, the implementation has critical runtime errors that must be fixed before merging.

Critical Issues:

• ReadableSpan.to_json() method doesn't exist - will cause immediate runtime failure
• File opened in write mode ("w") overwrites all previous traces on each batch export, losing data

Suggested fixes:

• Use existing span_formatter utility or manually serialize span attributes
• Change file mode to append ("a") to accumulate traces across batches
• Add error handling for file operations

Confidence Score: 0/5

• This PR cannot be merged - it contains critical bugs that will cause runtime failures
• The FileSpanExporter calls a non-existent method (span.to_json()) which will immediately fail when the local export path is used. Additionally, the file overwrite issue will cause data loss. These are not edge cases but fundamental issues in the core functionality.
• langfuse/_client/span_processor.py requires immediate attention to fix critical bugs

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Initialize LangfuseSpanProcessor] --> B{Check Environment Variables}
    B --> C{Is LANGFUSE_OTEL_TRACES_EXPORT_LOCAL_FILEPATH set?}
    C -->|Yes| D{Is LANGFUSE_OTEL_TRACES_EXPORT_PATH unset?}
    C -->|No| E[Use OTLPSpanExporter]
    D -->|Yes| F[Use FileSpanExporter]
    D -->|No| E
    F --> G[Export spans to local file]
    E --> H[Export spans to remote endpoint]
    G --> I[Write JSON to file per batch]
    H --> J[Send OTLP format via HTTP]

_{Last reviewed commit: 38937af}

_{(2/5) Greptile learns from your feedback when you react with thumbs up/down!}